✅ DCO Check Passed

Thanks @vagenas, all your commits are properly signed off. 🎉

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

🟢 Require two reviewer for test updates

Codecov Report

❌ Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.

📢 Thoughts on this report? Let us know!

Hi Everyone,

I'm using Docling's basic OCR to convert a PDF into text, and I save the output as a JSON file. In one of the PDFs I'm processing, the JSON result includes a group (Group 4), which lists its children as references to texts 61 through 77. Here's a simplified version of what the original JSON looks like:

"group": {
  "label": "form_area",
  "children": [
    {"$ref": "#/texts/61"},  // label: text
    {"$ref": "#/texts/62"},  // label: text
    {"$ref": "#/texts/63"},  // label: text
    {"$ref": "#/texts/64"},  // label: text
    {"$ref": "#/texts/65"},  // label: text
    {"$ref": "#/texts/66"},  // label: text
    {"$ref": "#/texts/67"},  // label: section_header
    {"$ref": "#/texts/68"},  // label: text
    {"$ref": "#/texts/69"},  // label: list_item
    {"$ref": "#/texts/70"},  // label: text
    {"$ref": "#/texts/71"},  // label: list_item
    {"$ref": "#/texts/72"},  // label: text
    {"$ref": "#/texts/73"},  // label: text
    {"$ref": "#/texts/74"},  // label: text
    {"$ref": "#/texts/75"},  // label: text
    {"$ref": "#/texts/76"},  // label: text
    {"$ref": "#/texts/77"}   // label: text
  ]
}

However, after loading this JSON using:

self.docling_doc = DoclingDocument.model_validate(doc_dict)

…the children list in Group 4 unexpectedly changes. Here's what I get after validation:

[
  RefItem(cref='#/texts/61'),
  RefItem(cref='#/texts/62'),
  RefItem(cref='#/texts/63'),
  RefItem(cref='#/texts/64'),
  RefItem(cref='#/texts/65'),
  RefItem(cref='#/texts/66'),
  RefItem(cref='#/texts/67'),
  RefItem(cref='#/texts/68'),
  RefItem(cref='#/groups/45'),  # Unexpected
  RefItem(cref='#/texts/69'),
  RefItem(cref='#/groups/44'),  # Unexpected
  RefItem(cref='#/texts/70'),
  RefItem(cref='#/texts/71'),
  RefItem(cref='#/texts/72'),
  RefItem(cref='#/texts/73'),
  RefItem(cref='#/texts/74'),
  RefItem(cref='#/texts/75')
]

Notably:

groups/44 and groups/45 were inserted automatically,

texts/76 and texts/77 are now missing from the group.

Is this due to the list_item labels (texts/69 and texts/71) not being inside a proper list group? I’ve seen references in the source where validation enforces list_item to be wrapped in a ListGroup, and I'm wondering if this restructuring is caused by that. It seems simliar error to the above pull request

Is there a recommended way to handle this — should I be wrapping any list_item in a separate group before validation to prevent auto-generated groups?

Happy to provide a more complete sample if needed.

Thanks in advance!